Aminet 35

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 35 / Aminet 35 (2000)(Schatztruhe)[!][Feb 2000].iso / Aminet / dev / src / stefanb_src.lha / UMS / Developer / doc / english / ums.doc next >

Wrap

Text File | 1995-05-13 | 76.9 KB | 2,086 lines

TABLE OF CONTENTS ums.library/--background-- ums.library/--loginguide-- ums.library/--message-format-- ums.library/--attributes-- ums.library/UMSCannotExport ums.library/UMSDeleteMsg ums.library/UMSDupAccount ums.library/UMSErrNum ums.library/UMSErrTxt ums.library/UMSErrTxtFromNum ums.library/UMSExportedMsg ums.library/UMSFreeConfig ums.library/UMSFreeMsg ums.library/UMSLog ums.library/UMSLogin ums.library/UMSLogout ums.library/UMSMatchConfig ums.library/UMSReadConfig ums.library/UMSReadMsg ums.library/UMSRLogin ums.library/UMSSearch ums.library/UMSSelect ums.library/UMSServerControl ums.library/UMSWriteConfig ums.library/UMSWriteMsg ums.library/--background-- ums.library/--background-- $VER: 11.27 (12-May-95) COPYRIGHT This document is (C) 1992-1995 by Martin Horneffer, Olaf Peters, Christoph Viethen, and ??? It may freely be copied and distributed, as long as the text is unchanged and this copyright notice is left intact. GENERAL UMS stands for "Universal Message System". This means that UMS allows to treat and read all kinds of messages ('e-mail' and 'news') as universally and efficiently as possible. The user should not need to care about what network a message comes from or goes to/through and what format is used, he or she should be able to concentrate totally on the messages' contents. In order to achieve this goal, UMS does two things: 1) define an universal format for messages where messages in all formats and from all networks can be stored in without loss of information and nevertheless being randomly interchangeable. This universal message format is described in this document in section "--message-format--". 2) implement a central, network-independent database-mamagement that allows to store and read/retrieve messages in the UMS format as efficiently as possible. The implementation of the Message Base Processor ('MBP') is based on the server/client- concept. Clients address the server to get or put messages. The server manages the storage and retrieval of messages and controls the different client's access-rights to the system. The common interface between client and server is a set of functions described in this document. Clients are - simple USERS that read and write messages (using programs called 'newsreaders'), - a special kind of user, the 'SYSOP', which has additional rights and tools to manage the system, - IMPORTERS, that get messages form other systems and put them into the local system after converting them to the UMS format, and - EXPORTERS, that look for all NEW messages in the system and send them to other systems after converting them into the specific format. The MBP controls which user may read what message and, in the same way, which exporter needs to export or forward what message. It cares about whether a message can or cannot be correctly sent to its destination. The MBP also performs dupe-checking and reply-chaining on Message-IDs. TAGS UMS extensively uses AmigaDOS-style tags (see: utility.library). In addition to the AmigaDOS standard, UMS uses some bit-masking in the types of tags: if bit 13 is set (tag & 0x2000), the tag data is a STRPTR, i.e. a pointer to a null-terminated string. if bit 14 is set (tag & 0x4000), the tag is considered a 'var- parameter' (e.g. LONG *). I.e. the tag.data entry must contain a pointer to the real data, which will be set/changed by the called function. if both bits 13 and 14 are set ((tag & 0x6000)==0x6000), the tag is a pointer to a string pointer which will be set/changed (STRPTR *). if none of these bits is set, the data in most cases is a simple integer parameter (e.g. LONG or LONGBITS). Exceptions are possible and explicitly mentioned. ums.library/--loginguide-- PURPOSE Guidelines on a uniform login-procedure in UMS-applications NOTE Suggestions concerning this section of the document should be directed to Olaf Peters <op@hb2.maus.de> GENERAL Shell- & Workbench-startup An application should take into account the command line arguments (Shell) respectively Workbench tooltypes 'NAME', 'PASSWORD' and 'SERVER'. Concerning invokation from a Shell, the order of arguments should match above example, with 'SERVER' declared a keyword (resulting in a command template beginning "NAME,PASSWORD,SERVER/K[,...]"). SHELL Invocation from Shell: If the application is passed a questionmark as the only argument on the command line (i.e. 'UMSapp ?'), it should return the template to stdout and offer a prompt to have the user enter the desired options. The user should be able to request additional help by responding to the prompt with another questionmark. Additional help consists of complete version information (at least a standard version template as specified in "Amiga User Interface Styleguide" (pp. 110)) accompanied by short help information. Technical realisation: DOS.ReadArgs() provides a standard means to parsing the command line and behaves exactly in the above described manner (it should therefore be used). Additional help text can be passed to ReadArgs() by supplying a custom RDArgs structure as third argument which holds a pointer to the text string in RDA_ExtHelp. Refer to "The AmigaDOS Manual", Chapter 5, Basic Input and Output Programming, Standard Command Line Parsing (pp. 181 as of the 3rd edition) GUI Applications allowing login via GUI (graphical user interface): If 'NAME' is not specified at startup time, it must be entered to the login window. Activate the name object. It is legal to pass an empty 'PASSWORD' as long as a name is specified. Thus the empty password must attempt a login! If the user passes the period (".") as 'PASSWORD', she desires to enter her password to the login window. It should open with the password object activated. If there is no 'SERVER' specified and the login window must be opened due to the above guidelines, the server object should be filled with the name of the default server (i.e. the server to which the user would be going to log in to if she was not naming a different one herself). The default server's name can be read from the ENV $UMSSERVER. If the ENV does not exist, the default name is "default". :-) A failed GUI login should be answered in a requester. After confirmation the user should be presented with the unmodified login window again as to correct her wrong inputs. Cancelling the requester should result in terminating the application. ums.library/--message-format-- ums.library/--message-format-- NAME UMS Message Format -- the universal format of UMS messages NOTE Suggestions concerning this section of the document should be directed to Christoph Viethen <cv@nostlgic.oche.de>. GENERAL A message in the UMS message base is always defined by a list of tags. This allows for easy extension as new tags may always be defined later on. In one UMS message, each tag may occur only once. TEXT TAGS The first part of this section describes the format of the currently defined TEXT-tags. Currently these tags include all information that is site-independend and needed when transferring messages between different systems. Except when explicitly stated otherwise, these tags are network- independent. Drivers for all networks can and must understand them. A text-tag specifies a null-terminated string of any length. All ASCII-characters are allowed. Unless something else is documented for a specific tag, the standard Amiga charset (ISO 8859 Latin 1) is used for 8-bit characters. Some of the text-tags are required for every message, others are optional. 0. UMSCODE_MsgText This contains the main 'text' of a message. Every message must have this tag as it is usually the main information transported by a message. Any information that does not belong to the original text must not be put here. Even when a gateway between two different networks puts information in the text, an UMS importer should - if possible - extract this information and use or store it somewhere else. The text may be of any size, even empty. By using the global ums.config item "Maxmsgsize" you can set a size limit. Attempting to _write_ messages larger than this into the message base will fail. (This limit does not affect the size of messages already in the message base. If you, say, write a message of 500K into the MB and then set "Maxmsgsize" to 300000 (bytes), there shouldn't be any problems when making read accesses to this message.) Since some networks limit messages to a certain size, drivers for these networks must be able to cope with this situation. Lines are delimited by the standard line delimiter (LF in the current UMS implementation), no matter, what network the specific messages originate from and what kind of line delimiters are used there. Lines may be of any length, so it's up to the newsreader or exporter to wrap lines if needed. 1. UMSCODE_FromName This is the name of the message's author. It's only the name and NOT the address. This should be the REALNAME! If there is no realname, the username must be used or extracted from the author's address. Every message must have this tag. 2. UMSCODE_FromAddress This is the author's net-address. The name needn't redundantly be repeated in this field, if it's already in UMSCODE_FromName. This tag must be empty or the tag must not be specified, if the author is located on the local system. In every other case, this tag is mandatory. Whenever possible, the address should be the user's real address and not an encapsulated address or the address of a gateway. Thus it may be necessary for importers to convert received addresses to another network's format. The corresponding exporters, of course, have to be able to re-convert these addresses. This makes the use of gateways transparent to the user - one of UMS' most important features. It saves the user from having to know and worry about the formats of all the gateways himself. Since there are different networks with different formats of addresses, it's neccessary to distinguish these different formats. This is done by looking at the "tail" of the address. The following formats are currently known: Identifier : network/format ---------------------------------------------------- "@Fidonet" : FidoNet ".maus" : MausNet ".org", ".edu", ".UUCP", ".net", ".de", .. [any valid usenet domain] : RFC "@BIX" : BIX "@Portal" : Portal Important note: Under certain circumstances, other identifiers may be used: 1) Small networks: Quite a few of them use adresses which look like FidoNet-Adresses, but contain a different "zone number". For practical reasons, messages from such networks may be imported into the UMS message base using an identifier other than "@Fidonet". So you may encounter addresses like e.g. "21:100/1.0@Gernet" in the MB. 2) There are special-purpose applications, like e.g. QWK im-/ exporters(?), which could use other kinds of identifiers not contained in the above table. So programmers of UMS applications should keep the following in mind: Any UMS tool should be programmed in such a way that it does not break if it encounters unknown network identifiers and/or formats. In such cases, it should inform the user of the problem and behave "neutrally", e.g. ignore the problematic message. UMS tools should never rely on somewhat adventurous "address format guessing" methods. On the other hand, if you plan to write a tool that will import messages into the MB with address formats different to the ones mentioned in the above table, you are _strongly_ advised to contact authors of other UMS applications, especially the developers of the UMS im-/exporters, in order to avoid incompatibility problems right from the start. Examples: a) Fidonet 2:2452/107.9@Fidonet 2:242/53@Fidonet b) MausNet AC2.maus MS.maus MK2.maus M.maus c) RFC maho@dfv.rwth-aachen.de marvin@tornado.oche.de in-info@individual.net postmaster@germany.uucp peterk@cbmger.de.so.commodore.com Network-identifiers are NOT case-sensitive. Nevertheless, you always should preserve case, as it might be needed by some networks. Historical note: Some time ago, a special address format was used in the german "Z-Netz", and its identifier was ".zer". That format had a number of limitations and disadvantages, so a new mail format called "ZConnect" was developed and now should be used by all Z-Netz members. This new format no longer needs any special address identifiers since it uses real RFC addresses. So the identifier ".zer" mentioned in the V10 version of this documentation shouldn't be treated in a special way by programs using ums.library any more. Some examples for splitting addresses for 'Name' and 'Address': RFC: "Martin Horneffer <maho@umshq.dfv.rwth-aachen.de>" -> name: "Martin Horneffer" address: "maho@umshq.dfv.rwth-aachen.de" "horneff@pool.informatik.rwth-aachen.de (Martin Horneffer)" -> name: "Martin Horneffer" address: "horneff@pool.informatik.rwth-aachen.de" "horneff@pool.informatik.rwth-aachen.de" -> name: "horneff" address: "horneff@pool.informatik.rwth-aachen.de" FidoNet: "Martin Horneffer at 2:242/7.9" -> name: "Martin Horneffer" address: "2:242/7.9@Fidonet" "Joerg Gutzke at 2:242/7" -> name: "Joerg Gutzke" address: "2:242/7@Fidonet" 3. UMSCODE_ToName Name of the person the message is addressed to. Must be specified in all private messages ("e-mail") and is optional in public messages ("news"). 4. UMSCODE_ToAddress The addressed person's network address. Needed in private messages if the message has not yet reached its destination. Must not be used when the mail is addressed to a user on the local system. UMSCODE_ToName and UMSCODE_ToAddress have exactly the same format as UMSCODE_FromName and UMSCODE_FromAddress. It should always be possible to reply to a private or public message by using it's FromName and FromAddress as the new ToName and ToAddress. 5. UMSCODE_MsgID A unique message ID in RFC-format. This is valid also for non-RFC networks like FidoNet or MausNet! Every message must have such an ID. If there's no ID for a message, the message base processor will create a new one for this message. Never create message IDs on your own! Some example message ID's, just to give you an idea what IDs from RFC and non-RFC systems may look like within UMS: 2pocc6$qf2@Germany.EU.net 295@lyssa.owl.de (generated by RFC systems) 91102312@p27.f107.n2452.z2.fidonet.org (generated by a Fido "point") 51515153@f7.n242.z2.fidonet.org (generated by a "non-point") 199409281223.a27374@hro.maus.de (generated in MausNet) 6. UMSCODE_CreationDate (Optional) date of creation, i.e. when the message has been written by the user. May be in any format that is readable by humans. AmigaDOS format (dd-mmm-yy hh:mm:ss) preferred. If not set, then the message base processor will use the current date to create a date string in AmigaDOS format. 7. UMSCODE_ReceiveDate Obsolete. Don't use any more! As a replacement there is a tag for a site-specific binary date. 8. UMSCODE_ReferID (Optional) message ID of the most recent message that is referred to by the current message. Same format as 'MsgID'. 9. UMSCODE_Group Name of the message's newsgroup. Must be used for public messages only. Must not be used for private mail. This tag is the only one that distinguishes private from public messages. To avoid possible conflicts, the name of the network must be prepended for non-usenet groupnames. Usenet groupnames, which already are hierarchically ordered, stay as they are. E.g. "fidonet.AMIGA", "maus.ac.amiga", "comp.sys.amiga.misc". Only one group may be used in this field! Use 'Hardlinks' for "crosspostings". 10. UMSCODE_Subject The (short) subject of the message. Required. 11. UMSCODE_Attributes (Optional) List of keywords. See ums.library/--attributes-- 12. UMSCODE_Comments (Optional) all "header-"information, that belong to a message and must be preserved, but don't fit to another text-tag. E.g. all unknown RFC-header lines go here. The first line should specify the name of networks the message comes from and the name (and perhaps version) of the importer. 13. UMSCODE_Organization (Optional) sender's organization or, in FidoNet, "Origin". 14. UMSCODE_Distribution (Optional) where/what the message should be distributed to/by. Much like RFC-"Distribution:". Could e.g. be used to select which UMS-Exporter should export the respective message if the ums.config is set accordingly. 15. UMSCODE_Folder (Written by receiver) The receiver of a private message may use this field to store a short label in (not more than about 30 chars, not more than one line). This allows him to categorize received messages. Newsreaders may allow to change that field for private messages and then to use these categories or 'folders' like 'groups' in public messages. 16. UMSCODE_FidoID This is specific to FidoNet. It should thus be ignored by all programs not specifically dealing with FidoNet. It's used to keep the internal "^aMSGID" used within FidoNet if it cannot be converted to 'MsgID'. This only applies to messages that came from other networks and went to FidoNet through some gateway. 17. UMSCODE_MausID This is specific to MausNet. It should thus be ignored by all programs not specifically dealing with MausNet. It's used to store the internal MausNet-ID. It will become superfluous when MausNet software learns to deal with real Message-IDs. 18. UMSCODE_ReplyGroup (Optional) name of the group public replies ("follow-ups") should go to. Ergo: Same purpose as "Followup-To:" in RFC1036. If not empty, newsreaders should copy this to the UMSCODE_Group field of the new message when writing a (public) follow-up. Otherwise keep the old UMSCODE_Group field. Same format as for field UMSCODE_Group, except that, if the author of the public message thinks that public replies should go into several groups (as a "crossposting"), he may enter a list of groups, seperated by commas, into this field. Exception to all of this: If this field contains the string "poster", this expresses the poster's wish to get a private reply. Newsreaders and similar UMS tools should behave accordingly. 19./20. UMSCODE_ReplyName/UMSCODE_ReplyAddress (Optional) name and address of the user private replies should go to. Same purpose as "Reply-To:" in RFC822. If not empty, newsreaders should copy these to the 'ToName' and 'ToAddress'-fields of the new message when writing a private reply. Otherwise 'FromName' and 'FromAddress' should be used. Same format as for 'ToName' and 'ToAddress'. 21./22. UMSCODE_LogicalToName/UMSCODE_LogicalToAddress (V11) These fields are needed in UMS systems involved in automatic mail distribution/forwarding, mailing lists e.g. Under such conditions, it may be necessary to differenciate between "physical" and "logical" addresses. While physical addresses describe the systems messages are indeed transported between, logical addresses describe what origin and destination the original author intended for his mail. If these fields are used, the fields UMSCODE_ToName and UMSCODE_ToAddress contain the respective physical address. These fields are optional - and usually not needed. 23. UMSCODE_FileName (V11) (Optional) In a first attempt to encourage the support of binary messages, UMS supports the notion of "attached files". A binary file may be attached to each message. If so, this field contains the logical name of the attached file. No assumptions are made concerning the style of the logical filename. 24. UMSCODE_RFCMsgNum (V11) Private field for an NNTP daemon service or UUNEWS: emulator. 32. UMSCODE_FidoText This is specific to FidoNet. It should thus be ignored by all programs not specifically dealing with FidoNet. It's used by FidoNet drivers to avoid loss of informa- tion due to conversions of eol-delimiters or charsets. 33. UMSCODE_ErrorText This is private to the MBP and a very special utility called 'bounce-daemon'. It is used to transfer an error-text for writing bounce-mails. No programs except of the 'bounce-daemon' should deal with it. 34. UMSCODE_Newsreader (Optional) name and version of the tool the message was created with. No specific format, but should be as small as possible. Not more than one line. 35. UMSCODE_RfcAttr Private field for RFC exporters. The user can supply additional information or hints to the exporter. 36. UMSCODE_FtnAttr Private field for FTN exporters. The user can supply additional information or hints to the exporter. 37. UMSCODE_ZerAttr Private field for Z-Netz exporters. The user can supply additional information or hints to the exporter. 38. UMSCODE_MausAttr Private field for Maus exporters. The user can supply additional information or hints to the exporter. 127. UMSCODE_TempFileName (V11) (Optional) This tag is related to UMSCODE_FileName. If a file is attached to the message, this field contains the "temporary" name of the attached file. It has only a local meaning and may be different when reading and writing. When writing the message, the client must supply the file with this temporary filename and the MBP must be able to read it. When reading the message, the MBP supplies the name to a file the client may read. The contents of this field could be eqaul to UMSCODE_FileName, but don't need to. Client as well as MBP have to use suitable path in the filesystem, and specify the full pathname. ums.library/--attributes-- ums.library/--attributes-- ums.library/UMSCannotExport ums.library/UMSCannotExport NAME UMSCannotExport -- Mark a message as not being exportable. SYNOPSIS UMSCannotExport( login, msgNum, error ) D2 D3 D4 VOID UMSCannotExport( LONG, LONG, STRPTR ); FUNCTION Tell the MBP that you cannot export this message, due to any reason. The MBP will then look if other exporters still could be able to export the message or do some error processing otherwise. It may use the supplied error-string therein. This error-string should be a short description why the message could not be exported. By convention it should not be longer than 80 bytes. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() msgNum - Number of the message. error - Short string (<80 chars). NOTES This function may only be called by exporters. The MBP currently does not write a bounce mail to the author of the mail, but sets a special global bit instead, which would allows the 'bouncer' tool to automatically write bounce mails. SEE ALSO UMSExportedMsg() ums.library/UMSDeleteMsg ums.library/UMSDeleteMsg NAME DeleteUMSMsg -- Delete a message. SYNOPSIS success = DeleteUMSMsg( login, msgNum ) D0 D2 D3 BOOL DeleteUMSMsg( LONG, LONG); FUNCTION This functions deletes a message, specified by number, from the UMS MB. It does not necessarily free space on the hd, but it removes the message logically from the MB so that no other user can access it anymore and it won't affect the dupe-check for new messages. The MBP may need reorganization to physically remove logically deleted messages. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() msgNum - Number of the message to be deleted. As returned by UMSSearch() or WriteUMSMsg(). RESULT success - Inidcates whether the message was actually deleted or not. It will be not deleted if you don't have write-access to this message or the message doesn't exist. NOTES The number of a message is valid only as long as you are logged in. After UMSLogout() messages numbers may change! So you always have to use the real Message-ID to remember a message persistently. ums.library/UMSDupAccount ums.library/UMSDupAccount NAME UMSDupAccount -- share a login handle between processes SYNOPSIS login = UMSDupAccount(login) D0 D2 UMSAccount UMSDupAccount(UMSAccount); FUNCTION UMSDupAccount() allows to share login handles to be shared between different processes. A login handle as returned by UMSRlogin() may onle be used the the same process that obtained the login. If it wishes to shared this login with other processes, the handle has to be 'dupped': the login handle is passed to the new process, which may _only_ uses this login with UMSDupAccount(). If successfull, a new login handle is returned, which (only!) can be used by the new process. This procedure is required to manage process-specific resources a login handle may depend on. It does _not_ create a new login on the server. Most likely, the server will not be involved in this procedure at all, it's all done on the client side. Each process must UMSLogout() all login handles it obtained either from UMSRLogin() or from UMSDupAccount(). The server only notices a logout, when all login handles concerning that login are closed with UMSLogout(). Order or login and logout, however, does not matter. E.g. the first process may UMSLogout() and terminate, while the new process ist still running and using a dupped login handle. Obviously the login handle has to be active at the time UMSDupAccount() is invoked, but it may be closed as soon as UMSDupAccount() has returned. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() RESULT login - Handle number if successful or Zero on failure SEE ALSO UMSLogin(), UMSRLogin(), UMSLogout() ums.library/UMSErrNum ums.library/UMSErrNum NAME UMSErrNum -- Return the number of the last error SYNOPSIS error = UMSErrNum(login) D0 D2 UMSError UMSErrNum(UMSAccount); FUNCTION UMS functions usually return zero to indicate an error. When this happens, this routine may be called to get a more specific error code. By some means, this routine corresponds to an UMS login as dos.library/IoErr() does to a DOS-process. Possible UMS errors are: 0 : No error at all, the last UMS function call was successful. 100-199: A slight error. The last functions call was not successful, but may succeed if some slight changes will be made to its parameters. 200-299: A real error. The last function call was not successful at all and should not be retried. 300- : A severe error concerning the whole system, e.g. the server has terminated. A program receiving such an error is recommended to UMSLogout() and terminate as soon as possible. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() RESULT error - Error number SEE ALSO UMSErrTxt() ums.library/UMSErrTxt ums.library/UMSErrTxt NAME UMSErrTxt -- Return a string describing the last error SYNOPSIS text = UMSErrTxt(login) D0 D2 STRPTR UMSErrTxt(UMSAccount); FUNCTION When an UMS function fails and/or UMSErrNum() returns a nonzero value, you should use this routine to get a brief English description of the last error. Interactive programs should display this text to the user. Non-interactive programs should use this text in their logfile. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() RESULT text - Pointer to a constant string NOTES This is similiar to dos.library/Fault(), but it doesn't copy any string, it just returns a pointer. You may NEVER change the string returned by UMSErrTxt()! SEE ALSO UMSErrNum(), UMSErrTxtFromNum() ums.library/UMSErrTxtFromNum ums.library/UMSErrTxtFromNum NAME UMSErrTxtFromNum -- Return a string describing the last error SYNOPSIS text = UMSErrTxtFromNum(error) D0 D2 STRPTR UMSErrTxtFromNum(UMSError); FUNCTION When an UMS function not related to an UMSAccount returns an nonzero value, you should use this routine to get a brief English description of the last error. Interactive programs should display this text to the user. Non-interactive programs should use this text in their logfile. INPUTS error - UMS error code RESULT text - Pointer to a constant string NOTES This is similiar to dos.library/Fault(), but it doesn't copy any string, it just returns a pointer. You may NEVER change the string returned by UMSErrTxtFromNum()! SEE ALSO UMSErrTxt() ums.library/UMSExportedMsg ums.library/UMSExportedMsg NAME UMSExportedMsg -- Mark a message as being successfully exported. SYNOPSIS UMSExportedMsg( login, msgNum ) D2 D3 VOID UMSExportedMsg( LONG, LONG ); FUNCTION Tells the MBP that a message has been successfully exported. The MBP uses this information to prevent other exporters from wrongly exporting this message a second time or writing a bounce message. Every exporter that exports a message from the local UMS system to any other system or network MUST call either UMSExportedMsg() or UMSCannotExport() for each message it has processed. This is valid for private messages as well as for public messages (news). The MBP will decide what has to be done in any of these cases. INPUTS msgNum - Number of the exported message. NOTES This function may only be called by exporters. SEE ALSO UMSCannotExport() ums.library/UMSFreeConfig ums.library/UMSFreeConfig NAME UMSFreeConfig - Free a string returned by UMSReadConfig() SYNOPSIS UMSFreeConfig( login, string) D2 D3 void UMSFreeConfig( LONG, STRPTR ); FUNCTION Frees the buffer allocated for a string and returned by UMSReadConfig(). After 'UMSFreeConfig(string)', 'string' will no longer be valid. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() string - string to be freed as returned by UMSReadConfig() SEE ALSO UMSReadConfig() ums.library/UMSFreeMsg ums.library/UMSFreeMsg NAME UMSFreeMsg -- Free buffers associated with a certain message. SYNOPSIS UMSFreeMsg( login, msgNum ) D2 D3 UMSFreeMsg( LONG, LONG ); FUNCTION Frees all the buffers associated with a certain message. ReadUMSMsg() allocates the buffers, this function frees them. INPUTS msgNum - number of the message previously read with ReadUMSMsg(). NOTES With UMSFreeMsg() all STRPTRs obtained with ReadUMSMsg() that are concerned with this certain message become invalid. You can have multiple ReadUMSMsg() on the same message but only one UMSFreeMsg(). SEE ALSO ReadUMSMsg() ums.library/UMSLog ums.library/UMSLog NAME UMSLog -- Write an entry to the global UMS logfile SYNOPSIS UMSLog(login, level, format, ...) D2 D4 D5 D6 void UMSLog(UMSAccount, LONG, STRPTR, ... ); UMSVLog(login, level, format, args) D2 D4 D5 D6 void UMSVLog(UMSAccount, LONG, STRPTR, APTR); FUNCTION Write a short message to the UMS logfile, doing printf()-style formatting on supplied parameters. Rather than creating its own logfile, an application should use this function to report its actions and/or errors. This makes it easier for the user to get an overview on what is happening in his system - he only has to look in ONE logfile. UMSLog() uses a 'level' parameter to decide whether a message should actually be written to the logfile or be ignored. The lower this number, the more important is the message. Choose it as follows: 1-4: An ERROR. 1 = fatal error, 4 = recoverable error. 5-7: General information or report. 8-9: Information that is not useful for normal operation, but used for debugging purposes. Of course messages with high level values should appear more frequently than those with low level values. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() level - Number between 1 and 9 format - printf()-style format string. See exec.library/RawDoFmt() for more information on formatting. args - Arguments for the format string SEE ALSO exec.library/RawDoFmt() ums.library/UMSLogin ums.library/UMSLogin NAME UMSLogin -- Obtain a login for access to the default message base SYNOPSIS login = UMSLogin(user, passwd) D0 D2 D3 UMSAccount UMSLogin(STRPTR, STRPTR); FUNCTION This function does the same as UMSRLogin(), but you cannot specify the message base. The default message base will be used instead. New programs shouldn't use this function. Use UMSRLogin() so that the user may specify a message base. INPUTS user - Name or 'alias' of an user passwd - The password of the user. A pointer to the null-string is allowed, NULL itself isn't. RESULT login - Handle number if successful or Zero on failure EXAMPLE UMSAccount login = UMSLogin("SysOp", "secret"); NOTE Never forget to call UMSLogout()! New programs shouldn't use this function. Use UMSRLogin() so that the user may specify a message base. SEE ALSO UMSLogout(), UMSRLogin() ums.library/UMSLogout ums.library/UMSLogout NAME UMSLogout -- Close a login and free its resources SYNOPSIS UMSLogout(login) D2 void UMSLogout(UMSAccount); FUNCTION Close a login obtained with UMSRLogin() and free all related resources. INPUTS login - Handle as returned by UMSLogin() or UMSRLogin() SEE ALSO UMSLogin(), UMSRLogin() ums.library/UMSMatchConfig ums.library/UMSMatchConfig NAME UMSMatchConfig -- Match a string against a config string. SYNOPSIS match = UMSMatchConfig( login, tags ) D0 D2 D3 BOOL UMSMatchConfig( LONG, struct TagIten * ); match = UMSMatchConfigTags( login, tag1, ... ) BOOL UMSMatchConfigTags( LONG, ULONG, ... ); FUNCTION UMS has its unique mechanism for pattern-matching, which is used by the MBP for determining different access-rights. UMSMatchConfig() offer direct access to this pattern-matching mechanism, including positive and negatibe config variables. A taglist is used to specify the string to be macthed as well as a UMS configuriation string serving as a pattern. INPUTS The functions takes two mandatory tags: MatchString : STRPTR specifies the string to be matched. MatchVarname : STRPTR specifies the name of the UMS config string. And there are some optional tags: MatchGlobalOnly : (none) only use a global config string. MatchUser : STRPTR use a config string local to another user. The name (or alias) of that user must be given. MatchDefault : LONG a value that will be returned, if the specified config string cannot be found, or any other type of error occurs. RESULT match - the result of the pattern matching. The value of tag MatchDefault or zero if an error occured. SEE ALSO UMSReadConfig() ums.library/UMSReadConfig ums.library/UMSReadConfig NAME UMSReadConfig -- Read an element from UMS' configuration. SYNOPSIS string = UMSReadConfig( login, tags ) D0 D2 D3 STRPTR UMSReadConfig( LONG, struct TagIten * ); string = UMSReadConfigTags( login, tag1, ... ) STRPTR UMSReadConfigTags( LONG, ULONG, ... ); FUNCTION Read an object from UMS' configuration. Whenever possible, applications should use the UMS configuration (as stored in the file 'ums.config' in the directory of the message-base) and the supplied functions UMSReadConfig() and UMSWriteConfig() instead of own special config-files. A 'config-string' is a null-terminated string identified by an unique name. Similar to shell- and environment-variables config-strings can be global (same for all users) or local (only visible to a certain user). Other config-objects are 'users' (with aliases and local strings), 'akas' and 'netgroups'. In order not to mix up config-strings of different applications, their names should have the id of the application and a dot prepended. E.g. "fido.outbound", "fido.inbound", "uucp.uuspool", "IntuiNews.QuoteChars.foo.bar", "ConfUMS.ForceDelete" etc. Names without a dot (".") are considered private strings of the MBP, e.g. "READACCESS", "WRITEACCESS". Names for config elements are case-insensitive. This function buffers the returned string until it is freed with UMSFreeConfig() or (UMSLogout()). INPUTS The following tags are allowed: CfgGlobalOnly : (none) read just global config-elements, ignore local ones. CfgUser : STRPTR read config elements local to another user. You must specify the name of the other user here. This contradicts CfgGlobalOnly (see above)! CfgLockVar : LONG (V11) using this tag you may preserve the config string from being modified by another login, i.e. another UMS program. Set the tag's data to 1 if you want to do so, otherwise use 0 (or do not use this tag) to not lock the variable. Be careful to unlock the variable if you do not need it anymore using UMSWriteConfig()'s tags CfgUnlockVar! This tag is useful only in conjunction with CfgName (see below). CfgQuoted : LONG (V11) read the variable in quoted format, as used in "ums.config". This enables you to mix the variable's data with macros. Set the tag's data to 1 if you want to use the quoted format, otherwise set it to 0 (or do not use this tag). The following tags are mutually exclusive. Use exactly one of them. The CfgNext-tags allow you to scan all the existing elements of one type and do all work in the same manner: On first invocation you set the tag's data to NULL and get the first element. With every further call, you set it to what has been returned on the previous call. When NULL is returned, you're done. CfgName : STRPTR read a config-string with given name. CfgUserName : STRPTR get the 'realname' for a user with a given alias. CfgNextVar : STRPTR get the name of the next config variable. This tag may be combined with tag CfgGlobalOnly or tag CfgUser (see above). CfgNextAlias : STRPTR (V11) get the next alias. This tags may be combined with CfgUser (see above) CfgNextUser : STRPTR (V11) get the 'realname' of the next user. CfgNextExporter : STRPTR (V11) get the name of the next export. CfgNextGroup : STRPTR get the name of the next netgroup. Any number of groupnames may be configured as identical 'netgroups'. Use this tag to scan all netgroups, to scan their members use CfgNextGroupMember (see below). CfgNextGroupMember : STRPTR (V11) get the name of the next member of a specific netgroup. Using this tag repeatedly you can cycle trough all groups belonging to the same netgroup. Members of netgroups are organized in a circular structure, so you'll have to compare the original string with every result to determine whether you're done. NULL is returned only if the given string doesn't indicate a valid netgroup-member. RESULT string - a pointer to the desired config element or NULL. SEE ALSO UMSFreeConfig(), UMSWriteConfig() ums.library/UMSReadMsg ums.library/UMSReadMsg NAME UMSReadMsg -- Read (parts of) a message. SYNOPSIS success = UMSReadMsg( login, tags ) D0 D2 D3 BOOL UMSReadMsg( LONG, struct TagItem * ); success = UMSReadMsgTags( login, tag1, ... ) BOOL UMSReadMsgTags( LONG, ULONG, ... ); FUNCTION Read a message or any parts of it. INPUTS The following tags are allowed: RMsgNum : LONG specify which msg to read. This tag MUST be used! RHeaderLength : LONG * you have to pass a pointer to a LONG here. This LONG will be set to the length of the message-header in bytes. I.e. the length of all text-fields considered to belong to the 'header' of a message. RTextLength : LONG * like RHeaderLength, but the length of the message-text. These are all other fields. RMsgDate : LONG * the date the message has been written to the message-base (also referred to as the 'receive-date'). In AmigaDOS Format (seconds since 1.1.1978). RChainUp, RChainDn, RChainLt, RChainRt : LONG * reply-chaining. Since a message can only refer to one other (older) message, but have multiple other (newer) messages referring to it, a tree is built out of this 'comment-chaining'. ChainUp points to the referred message. ChainDn points to one of the messages that comment on the current one. ChainLt and ChainRt point to other messages which share the same ChainUp. The LONG you supply a pointer to in the tag's data will either be set to zero (when there is no such chain) or to the number of a message. RGlobalFlags : LONGBITS * global flags for this message. In the MB every message has exactly one set of global flags. See <ums.h> for the meaning of these flags. RUserFlags : LONGBITS * user-flags for this message. Every user of the MB has one set of user-flags for each message. See <ums.h> for the fixed or suggested meanings of these flags. RLoginFlags : LONGBITS * login-flags for this message. Every login has a private set of flags for each message. In contrast to global or user-flags, login-flags are NOT saved and vanish on UMSLogout(). They are set to zero on UMSLogin(). RHardLink, RSoftLink : LONG * a pointer to another link in the circular linked list of linked messages. Zero if a real message (no link). Since message-links can be either hard or soft, but not both at the same time, only one of these can be non-zero. RDateStyle : LONG use this tag and set its data to 1 if you want to get an old-style 'receive-date'. Don't use this tag or set its data to zero otherwise. RMsgText, .. RMsgText + 127 : STRPTR * tell UMS that you want to read the specified text-field and supply a place for a pointer to it. This will be set to NULL if the field doesn't exist or you're not allowed to read it. RTextFields : UMSMsgTextFields if you supply a pointer to an array of 128 STRPTR here, it will be set to the read text-fields. Useful for reading a whole message without having to specify a tag for each possible text-field. RReadHeader : (none) tell UMS that you want to read all header-field. Useful in combination with RTextFields only. RReadAll : (none) tell UMS that you want to read the message-text, too. Useful in combination with RTextFields only. The following tag was not implemented in ums.library until V9.70 ! RIDStyle : LONG choose the style of local message IDs. There are two possible formats of 'local' message IDs (= the IDs created by the local system): a) a simple decimal number that is unique on the local system b) this decimal number followed by "@" and the domain- address of the local system. This conforms with RFC822/1036. Old (obsolete) Version of ums.library (< V9.70) still use format a), but since V9.70 versions use format b) in order to make things cleaner and make life easier for exporters. With format a) exporters must append the domain-address to IDs themselves, with format b) they needn't care about whether an ID is local or not. As an interim solution this tag allows to specify the desired format. Its data set to 1 forces format a), 0 (default) forces format b). RNoUpdate : LONG when reading its message-text, a message is usually updated by having its 'Old'-flag set in your user-status. If you don't want the Old-flag to be set, use this tag and set its data to 1. RESULT success - whether your attempt to read the message was successful or not. NOTES The message will be buffered, so you can easily use all the returned STRPTRs. You have to use UMSFreeMsg() to free the buffers allocated for a certain message. The string obtained by UMSReadMsg() are private copies for you - though not recommended, you may even overwrite them, but _never_ beyond the teminating zero-byte. UMSFreeMsg() still wroks if strings are modified. An user or exporter usually wants to read a single message only once. To make this easy, UMSReadMsg() checks whether the user reads the 'MsgText' of a message, and, if so, sets the 'Old'-Flag in the users status if it wasn't already set. So the user (or exporter) only needs to ask for this flag to be unset when using 'UMSSearch()' before 'UMSReadMsg()' and will automatically avoid reading the same message a second time. SEE ALSO UMSFreeMsg(), UMSSearch() ums.library/UMSRLogin ums.library/UMSRLogin NAME UMSRLogin -- Obtain a login for access to a message base SYNOPSIS login = UMSRLogin(server, user, passwd) D0 D2 D3 D4 UMSAccount UMSRLogin(STRPTR, STRPTR, STRPTR); FUNCTION This function is used to get access to an UMS message base. If necessary the UMSServer is launched first. ... This function returns a handle which is used internally to track and remember the resources associated with each login. If an user tries to login multiple times this handle will be different each time. A login may be used only by the process which created it UMSRLogin(). Zero on failure, any other value indicates success. INPUTS server - Name of the message base user - Name or 'alias' of an user passwd - The password of the user. A pointer to the null-string is allowed, NULL itself isn't. RESULT login - Handle number if successful or Zero on failure EXAMPLE UMSAccount login = UMSRLogin("TestServer", "SysOp", "secret"); NOTE Never forget to call UMSLogout()! Use this function instead of UMSLogin() for new programms. SEE ALSO UMSLogin(), UMSLogout() ums.library/UMSSearch ums.library/UMSSearch NAME UMSSearch -- Search a message from the MB. SYNOPSIS msgNum = UMSSearch( login, tags ) D0 D2 D3 LONG UMSSearch( LONG, struct TagItem * ); msgNum = UMSSearchTags( login, tag1, ... ) LONG UMSSearchTags( LONG, ULONG, ... ); FUNCTION Search the first (or next) message in the MB that fulfils certain criteria. When you want to read certain messages from the MB, it is recommended that you first select these messages with UMSSelect() and then alternately use UMSSearch() and UMSRead() to get all these messages. INPUTS Allowed tags: SearchLast : LONG specify the last message NOT to search. This tag allows you to cycle trough all messages fullfilling the same criteria: set this to zero and invoke UMSSearch() the first time. Check the result and if it's not zero, put it in this tag and invoke UMSSearch() again. Repeat this until it returns zero. SearchDirection : LONG set the search direction. 1 means search forward (to higher numbers), -1 means search backwards (to lower numbers) and 0 lets the MBP decide what sequence to use. This needn't be exactly forwards or backwards. It might be in a completely different order. When you don't depend on a certain search-direction, use 0 or omit this tag. SearchGlobal : (none) SearchLocal : (none) SearchUser : STRPTR SearchMask : LONGBITS SearchMatch : LONGBITS search for a matching status; like SelReadGlobal, SelReadLocal, SelReadUser, SelMask and SelMatch with UMSSelect(). WMsgText, .. WMsgText + 127 : STRPTR search for a matching text; as for UMSSelect(). Only one field can be searched for at a time. SearchQuick : (none) Enable 'quick-search'. This must be combined with exactly one of WMsgText+1 .. WMsgText+31. quick-searches are possible for exact string searches only, they must not be combined with patterns and they are only possible for fields that have an index. They don't guarantee that the returned message's field actually matches the given string, altough mistakes are very unlikely. But they are fast! (see NOTES below) SearchPattern : LONG indicate whether the string to be searched for is an exact string (0), an AmigaDOS pattern (1) or UMS should try to find out (2). RESULT msgNum - numer of a/the searched message; zero if not found. NOTES Although LONGBITS are used in the definition, the current implementation only uses/supports the lower 16 bits. Performance: when searching for strings, different calls to UMSSearch() may significantly vary in performance. There are three general possibilities: 1) quick-searches: very fast, no access to the hard-disk needed (once the right index is loaded into memory). Only possible if tag 'SearchQuick' specified. 2) indexed searches: fast, in most cases only one, short access to hd is needed; a few more in really bad situations. If the 'header'-file is sufficiently buffered, no accesses to the hd may occur. Possible if searching for exact strings in indexed fields. 3) other searches (non-indexed or patterns): slow, many data will have to be read from hd. If the field searched for is in the 'header'-file and it's heavily buffered, no accesses to the hd may occur. Nevertheless the search will consume much CPU-time. Search for status!!! Searching for a matching status only (i.e. not searching for a string) is always very fast. When doing non-indexed- or pattern-search, combine with status to reduce the amount of data to be searched through! SEE ALSO UMSSelect(), ReadUMS(), <ums.h> ums.library/UMSSelect ums.library/UMSSelect NAME UMSSelect -- Select messages. SYNOPSIS count = UMSSelect( login, tags ) D0 D2 D3 LONG UMSSelect( LONG, struct TagItem * ); count = UMSSelectTags( login, tag1, ... ) LONG UMSSelectTags( LONG, ULONG, ... ); FUNCTION Select messages in the MB according to various criteria. To 'select' here means to set or unset some flags, which then can be used by UMSSearch(), stored or transferred to another user. UMSSelect() can only do one operation upon every invocation. An operation usually looks for all messages that fullfill the specified criteria and then selects them in a specified way. When you want to select messages by different, logically combined criteria, you may need to call UMSSelect() more than once and use some temporary flags. However, very few calls to this functions usually should suffice. INPUTS The following tags control the selection of messages. Thus, they somehow specify the 'output' of the select operation. SelWriteGlobal : (none) manipulate global flags on the selected messages. SelWriteLocal : (none) manipulate your local login-flags. SelWriteUser : STRPTR manipulate another user's user-flags. You must specify the users name (or alias). SelWriteGlobal, SelWriteLocal and SelWriteUser are mutual exclusive -- you can manipulate only one flag-table at a time. When specifying none of these tags, your user-flags will be manipulated as default. SelSet, SelUnset : LONGBITS on each selected message the 'SelUnset' flags are cleared and then the 'SelSet' flags are set. ['status = (status & ~unset) | set;'] When writing global- or user-flags, you are not allowed to manipulate all possible flags. See <ums.h> for protected flags. The following tags control what and how messages are selected, the 'input' and 'modes' of the select operation. SelStart, SelStop : LONG Limit the number of messages to be processed. The select operation will start with the message indicated by 'SelStart' and stop before the 'SelStop' message. In other words, start is included and stop is excluded. (0 < start <= messages to be processed < stop) This was different and partly buggy in MBP versions prior to V10.16. If no 'SelStart' is specified, the operation starts with the first message; if no 'SelStop' is specified, the operation stops at the last existing message. The following seven operations are mutually exclusive: 1) select by status SelReadGlobal : (none) SelReadLocal : (none) SelReadUser : STRPTR like SelWriteGlobal, SelWriteLocal, SelWriteUser, but specifys which flags to look at. Again, your user-flags are the default. SelMask, SelMatch : LONGBITS specify a mask and a match. If (status & mask) == match [status * mask = match], the message will be selected. SelParent : (node) with this tag specified, each message's 'parent' (reference; -> reply-chaining) will be inspected instead of its own status. 2) select by date SelDate : LONG the messages' dates are compared with the supplied date (in seconds since 1.1.1978) and only the younger ones will be selected. 4) select a tree SelTree : LONG you must specify the number of a message here. Then all messages being in the same reply-tree will be selected. 5) select a sub-tree SelSubTree : LONG like SelTree, but only the subtree (the one with the specified message as its root) is selected. 6) select a single message SelMsg : LONG select only the specified message. 7) select by text WMsgText, .. WMsgText + 127 : STRPTR when you specify one of these tags, the function selects all messages which have the supplied string in the specified field. The strings are compared case-INsensitive. SelQuick : (none) when this tag is specified, 'quick-search' is enabled for selecting texts. This means that only some CRCs on the texts are compared. This makes it possible to select also some wrong messages. Yet, due to the usage of 32-bit CRCs, the probability of selecting wrong messages is VERY low, you most likely will never experience this case. As 'quick-search' does not usually need to access mass- storage, it is VERY FAST. RESULT count - how many messages have been selected. Zero, when no message has been selected or an error has occured. EXAMPLE See SelectMail.c for examples on how to use this function. NOTES Although LONGBITS are used in the definition, the current implementation only uses/supports the lower 16 bits. SEE ALSO UMSSearch(), <ums.h> ums.library/UMSServerControl ums.library/UMSServerControl NAME UMSServerControl -- control the UMS server. SYNOPSIS error = UMSServerControl(server, action) D0 D2 D3 UMSError UMSServerControl (STRPTR, LONG); FUNCTION This function does not take an UMS account as parameter, but simply the name of the server to address and an integer number for the action to the server is expected to perform. It "annonymously" controls the global behaviour of the server. The following actions are available: 1 = CleanUp Start the cleanup procedure, reorganizing the whole MB, physically deleting deleted and expired messages and freeing space on the HD. This procedure is critical, since the MB will be corrupted if the procedure is interrupted (by system failure, power-off, reboot, ..). Always make of backup of the MB before starting a cleanup! A cleanup is not possible if there are valid logins, since all message-numbers are changed. 2 = Flush Flush all buffers. 3 = Quit Terminate the server. If there still are logins, the server might pop up a requester to ask whether to quit or to continue, 4 = QuitForce Really terminate the server, no matter how many users still need it. No requester. 5 = Ping Test whether the addressed server is running. 6 = LockCfg Globally lock the UMS configuration against changes. 7 = UnlockCfg Release a lock optained with LockCfg. You should use LockCfg before and UnlockCfg after editing the file "ums.config" while the server is running. INPUTS server - name of the UMS server to control. action - no of action to perform. RESULT error - error number. SEE ALSO UMSErrTxt(), UMSErrNum() ums.library/UMSWriteConfig ums.library/UMSWriteConfig NAME UMSWriteConfig -- Write an element to the UMS' configuration. SYNOPSIS success = UMSWriteConfig( login, tags ) D0 D2 D3 BOOL UMSWriteConfig( LONG, struct TagIten * ); success = UMSWriteConfigTags( login, tag1, ... ) BOOL UMSWriteConfigTags( LONG, ULONG, ... ); FUNCTION Create or modify elements of UMS' configuration. INPUTS The following tags are allowed: (Note: talking about a 'user' means exporters and sysops as well.) CfgData (STRPTR) this tag's data holds the contents of the variable to be written. Use this tag in conjunction with CfgName (see below). CfgUser (STRPTR) name of the user whose local configuration should be changed. E.g. create a new alias or variable belonging to the specified user etc. CfgGlobalOnly (none) change an element of the global configuration area being readable by all users. CfgQuoted (LONG, V11) to store the variable's data in quoted format, allowing to mix the data and macro definitions, set the tag's data to 1 otherwise set it to 0 (or do not use this tag). CfgLocal (none, V11) use this tag to create or delete variables that are only valid with the current login, disappearing after UMSLogout(). This way you can easily use UMSMatchConfig() without actually modifying the "ums.config". CfgUnlockVar (STRPTR, V11) use this tag to unlock a variable locked by calling UMSReadConfig() with the CfgLockVar tag allowing "public" access again. Set the tag's data to 1 to unlock and store the variable and its data, set it to 2 to just unlock the variable without actually saving it and set it to 0 (or don't use this tag) to not care about the current locking state of the variable. The following tags are mutually exclusive. Use exactly one of them. CfgName (STRPTR) Name of the config variable to be changed. If a variable of the given name does not exist it will be created. To remove a variable from the configuration do not specify a tag CfgData (see above). CfgDump (STRPTR) write the current settings to a file with given name. CfgCreateAlias (STRPTR, V11) create a new alias of the given name for the user specified by the CfgUser tag (see above). CfgDeleteAlias (STRPTR, V11) remove the alias of the given name from the user specified by the CfgUser tag (see above). CfgCreateExporter (STRPTR, V11) create a new export user with the given name. CfgCreateSysop (STRPTR, V11) create a new user with sysop-privilegs with the given name. CfgCreateUser (STRPTR, V11) create a new user with the given name. CfgDeleteUser (STRPTR, V11) remove the user with the given name from the configuration deleting her local variables as well. CfgAddNetGroup (STRPTR, V11) CfgNetGroup (STRPTR, V11) add a netgroup entry. These two tags must be used together, each naming one group. These two groups then are considered to the of the same "netgroup". If there are more than two named for the same netgroup, repeat this function for each additional groupname, setting CfgNetGroup to the name of an already existing group. CfgDeleteNetGroup (STRPTR, V11) delete a netgroup entry. The named group will be removed from the configuration. RESULT success - whether it was possible and allowed to make the desired write or change. SEE ALSO UMSReadConfig() ums.library/UMSWriteMsg ums.library/UMSWriteMsg NAME UMSWriteMsg -- write a message to the UMS message base. SYNOPSIS msgNum = UMSWriteMsg( login, tags ) D0 D3 D3 LONG UMSWriteMsg( LONG, struct TagItem * ); msgNum = UMSWriteMsgTags( login, tag1, ... ) LONG UMSWriteMsgTags( LONG, ULONG, ... ); FUNCTION Writes a message to the UMS message base. This may be either a new message to create or an already existing message to be changed. The MBP checks correctness of the message and the users write-access concerning this message before writing it. It also performs dupe-checking, tries to link to a tree of reply-chains, creates all desired indices and computes the other users' read-access to this message. All the components of the message as well as information on how to do it are supplied as AmigaDOS compatible TagItems. INPUTS The following tags are allowed: WMsgText, .. WMsgText + 127 : STRPTR specify a certain text-field. A text fields is always one null-terminated string. Read the separate documantation to see what fields and what formats of these fields are allowed. A certain text-field (identified by its tag) may only appear once in a message. If a field is specified more than once in the tag list, only the latest will be used. WTextFields : UMSMsgTextFields specify more than one text-field. This points to an array of 128 string-pointers. All fields you don't want to specify must be NULL in this array. WMsgNum : LONG when you want to change an old message, you must use this tag to specify the number of the message to change. Don't use this tag when you just want to create a new message. WMsgDate : LONG this has a very special meaning. Specifying an AmigaDOS compatible date (seconds since 1.1.1978) with this tag indicates that you want to restore an old message from a backup rather than writing a new one. All users will have the 'old' flag set and not get this message as a new one when this tag is used. WChainUp : LONG in some cases it might be unsure or impossible for the MBP to build the correct reply-chain for a message. Use this tag to specify the number of the old message that is referred to by the new one. WHardLink, WSoftLink : LONG Writing a message with a Message-ID that already exists in the MB usually will lead to the detection of a 'dupe'. Yet in some cases it is necessary for UMS to allow multiple messages with the same Message-ID. This is made possible by the concept of message-'links'. With this concept, multiple messages sharing the same Message-ID (and perhaps some more fields) are organized in a circular linked list. To create such a linked list, you just write its first message as usual and remember its number. Then you write the other messages using one of the above tags to specify the number of the original message (or any of the already linked messages). The MBP may optimize storage space for message links by only storing the fields that differ between the fields and the original message. Nevertheless you always have to specify the whole message to write a link and you will always get the complete message when reading a link. All links to a message must consist of the same fields as the original message, but the contents of the fields may differ. There are two sorts of message-links, hardlinks and softlinks. Softlinks describe messages that have some fields in common (at least MsgID), but are really treated as individual messages. E.g. a mail with multiple receipients. Hardlinks, on the other hand, are treated as one message wherever possible. I.e. if you read one hardlinked message, all the other links will be marked as old, too. RFC crosspostings, for instance, should be made hardlinks. WAutoBounce : LONG If the msg to be written is addressed to a local user that doesn't exist or to an address that no exporter can export, there are two possible behaviours possible for the MBP: a) reject the message using error-no "NoReader", expecting the client to care about the undeliverable message b) keep the message, forwarding it to the local sysop or some kind of 'bounce-daemon', so that the writing client needs not to care about the message any more. This tag allowes to specify the desired behaviour, data=0 forces a), data=1 forces b). If this tag is not specified, the MBP will choose the behaviour as it wishes, maybe depending on whether the writing user is an exporter or not. WHide : LONG In some cases it might be desirable to write a message that can only by read by exporters and not by simple users, or the other way round. For instance control-messages that are of no interest to users by must be distributed over the net. Setting data to 0 is the same as the default. data=1 means that only exporters may view and read the message, data=2 makes the message invisible to exporters and only accessible to simple users. WHdrFill, WTxtFill : LONG specify how many bytes to reserve for later changes in the header/text of the message. The MBP may not be able to change an existing message if the change would increase the overall size (maybe after compression) of the message. Since such changes are neccessary in some special cases, the MBP can be told to reserve some space when writing a message the first time. Reserving more than actually needed is not a good idea, since it decreases performance and wastes space. The writer of a message usually should know whether or not he will change the message later on and to what extend he will increase the size of the message. WNoUpdate : LONG when writing a message, the 'Old'-flag in your user-status for the new message will usually be set. If you don't want this, use this tag and set its data to 1. WCheckHeader : LONG if you just want to check whether the MBP would likely accept a message but you don't yet have the complete body of the message, you can use this tag und set its data to 1: nothing is actually written to the MB. If the supplied message-header seems to be ok, -1 will be returned as a "fake" message number. Then you can get the messages body (e.g. transfer it over a network) and write the message with removing this tag of just setting its data to 0. RESULT msgNum - Number of the written message or NULL on failure. NOTES Changing an old message: You must _always_ give a complete message to UMSWriteMsg(), even when changing an old one! The MBP needs this to detect all changes made to the old message, including changed, added or deleted fields. Thus you need to read a message prior to changing it. Use RTextFields and WTextField for UMSReadMsg() and UMSWriteMsg() when changing an old message! Otherwise you will loose fields unknown to you allication that might be still important to other applications! You may not be allowed to change certain fields of an existing message. Most likely those fields that are used by the MBP to compute all the users access-rights will be prohibited to change.